/*
 * Copyright (c) 2013, Klaus Hauschild
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided
 * that the following conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright notice, this list of conditions and
 *     the following disclaimer.
 *
 *   * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
 *     and the following disclaimer in the documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
package de.hauschild.utilsn.core.gamestate;

import de.hauschild.utilsn.core.Entity;

/**
 * Describes a concrete state of game like "menu", "play field" or "game over". Use this to encapsulate the different
 * parts of game.
 * <p>
 * The lifecycle of a game state "a" and "b" looks like:
 * <ul>
 * <li><code>a.init()</code></li>
 * <li><code>a.enter()</code></li>
 * <li><code>a.exit()</code></li>
 * <li><code>b.init()</code></li>
 * <li><code>b.enter()</code></li>
 * <li><code>b.exit()</code></li>
 * <li><code>a.enter()</code></li>
 * <li><code>a.exit()</code></li>
 * <li><code>b.enter()</code></li>
 * <li><code>b.exit()</code></li>
 * <li>...</li>
 * </ul>
 * </p>
 * 
 * @since 0.1.0
 * 
 * @author Klaus Hauschild
 */
public interface GameState extends Entity {

  /**
   * Enters the game state. Set up the graphics and logic here.
   * <p>
   * This method is always called to enter the current game state right after leaving the previous one.
   * </p>
   * <p>
   * With <code>previousGameStateType</code> and <code>arguments</code> you can transport data from previous game state
   * to the current. This might be useful to transport players scores to a highscore screen for instance.
   * </p>
   * 
   * @param previousGameStateType
   *          the type of the previous game state, is <code>null</code> for the initial game state.
   * @param data
   *          the data from the previous game state
   */
  void enter(Class<? extends GameState> previousGameStateType, Object... data);

  /**
   * Leaves the game state. Do cleanup here.
   * <p>
   * This method is every time called to leave the current game state right before entering the next one.
   * </p>
   */
  void exit();

  /**
   * Initializes the game state. Do preparation and resource loading here.
   * <p>
   * This method will only called once.
   * </p>
   */
  void init();

}
